Skip to main content

Setting Up the Java RESTful Engine

Our Java RESTful engine can be hosted on a Windows or Linux machine under a Tomcat server. The engine utilizes the Spring Boot REST API Framework. The setup instructions for the engine are the same for both platforms.

Requirements​

To get the Java RESTful Engine running on your machine or server, you will need:

note

For the sake of this tutorial, we will be using Apache Tomcat server to host the Java RESTful engine. This does not mean you have to use tomcat, but can use any application server that can deploy WAR files.

  • A Fluent RESTful Engine license key (if you don't have one, you can sign up for a trial here)
  • The latest version of the Java RESTFul installation
  • Java 17 installed on your machine or server (Starting with Java RESTful engine 23.0.0. Previous versions require Java 8)
  • A Tomcat Server (V10) instance set up on your machine. If you are not familiar with Tomcat, follow this link to learn more. (Starting with Java RESTful engine 23.0.0. Previous versions require Tomcat 9)
  • Hardware
    • Processor: 2 GHz
    • Memory (RAM): 4 GB
    • Hard Disk: 300 MB free space

Setting Up Java RESTful Engine on Tomcat Server​

  1. Make sure you have a Tomcat Server (version 10) installed.

  2. Navigate to your Tomcat installation:

    • On Windows, it will most likely be here:
      • C:\Program Files\Apache Software Foundation\Tomcat 10.X
    • On Linux, it will most likely be here:
      • /opt/apache-tomcat-10.X

    img

  3. Shut down the tomcat server by navigating to the Tomcat/bin directory

    • On Windows, run the shutdown.bat batch file
    • On Linux, run the shutdown.sh shell script

    img

  4. Navigate to the /Tomcat/webapps directory

  5. Delete the ROOT directory in the /Tomcat/webapps directory img

  6. Now extract the "JavaRESTful-{version.number}.zip" file you downloaded earlier, and then navigate to the {version.number} directory. In there you will find:

    • App_Data directory
    • ROOT.war file
    • JavaRESTfulengine-{version.number}.pom file
    • Fluent Combined Software License Agreement 4-8-21.pdf

  7. Move the contents of the {version.number} directory into the /Tomcat/webapps directory img

  8. Now you can start the server by navigating to /Tomcat/bin

    • On Windows, run the startup.bat batch file
    • On Linux, run the startup.sh shell script

  9. The Java RESTful engine is now hosted on the Tomcat server under the root address you used during the Tomcat setup. Read the next section to see what to do with the Fluent RESTful Engine license key

    • If you are running the server on a Virtual Machine, you will be able to access the service via the machines public DNS if you setup the right ports.

Using the License Key​

The Java RESTful engine accepts the license key in two ways. You can either set it globally in the engine's properties file, or set it on a per request basis where you pass it as a header in the request.

  • To set it globally in the projects properties file:
    1. After the Tomcat server is running with the JavaRESTful Engine, navigate to /Tomcat/webapps/ROOT/WEB-INF/classes.
    2. Open WindwardReports.properties
      • Change the value of the property "license" to your license key
    3. Now the JavaRESTful Engine will use that license key for all requests.
  • To pass the license key as a request header for per request use:
    1. The key value for the header is "X-WINDWARD-LICENSE" and the value is your license key.
    2. You can use this if you wanted to use different license keys for different requests.

Property Files​

There are 3 total property files relevant to the Java RESTful Engine, you will find all of them in the /Tomcat/webapps/ROOT/WEB-INF/classes directory:

  1. WindwardReports.properties
    • This is the properties file for the actual underlying engine, and where you will set your license key for global Java RESTful use. This is the list of properties you can use.
  2. application.properties
    • This is the properties file for the Spring Boot REST API framework used. You can find a list of commonly used properties here.
  3. log4j2.xml
    • This is the properties file for the logger. You can find some more information here.
info

We ship these property files with the values we intended on using. Changing some values we have set may affect the expected behavior of the engine.

Log File​

As shipped, the Java RESTful Engine will write its log to the file "JavaREST.log" in the /Tomcat/logs directory.